Ethan's Notes

Appearance

初步解读 ​

1.1 总览 ​

顶层目录主要有： docs、scripts、src、stubs、tools、types、utils、vendor package.json、package-lock.json、tsconfig.json、README.md、README_CN.md、QUICKSTART.md

从结构上看，这是一个以 src 为主的 TypeScript/Node 项目，里面还有：

  • src/components：界面组件
  • src/cli：命令行相关
  • src/bridge：桥接/通信相关
  • docs/en|zh|ja|ko：多语言文档
  • tools/*：工具模块

1.2 架构分析 ​

这个项目可以理解成一个“终端 UI + 会话状态机 + 模型查询循环 + 工具系统 + 插件/MCP 扩展层”的 CLI Agent。

总览 最外层启动入口是 claude-code-source-code/src/entrypoints/cli.tsx，它先做参数分流： --version、daemon、remote-control、bg session、self-hosted-runner 这类走快速路径； 普通交互模式才会进入 claude-code-source-code/src/main.tsx。

main.tsx 是总装配层，负责：

  • 初始化配置、认证、遥测、GrowthBook、策略限制
  • 解析 CLI 参数和运行模式
  • 装载命令、工具、MCP、插件、agents
  • 构造初始 AppState
  • 生成 system prompt
  • 启动 REPL

真正渲染终端界面的是 claude-code-source-code/src/replLauncher.tsx 和 D:/project/ claude%20code%20source/claude-code-source-code/src/screens/REPL.tsx。replLauncher 只是把 App 容器和 REPL 组件挂起来， REPL.tsx 才是交互主控。

分层架构 可以把它拆成 6 层：

  1. 启动与模式分发 文件： claude-code-source-code/src/entrypoints/cli.tsx claude-code-source-code/src/main.tsx

职责：

  • 识别当前是普通 TUI、远程桥接、后台 session、daemon、SDK/print 模式
  • 做前置初始化
  • 进入交互或非交互执行路径
  1. 交互 UI 层 文件： claude-code-source-code/src/screens/REPL.tsx claude-code-source-code/src/components/App.tsx

职责：

  • 渲染消息列表、输入框、权限弹窗、任务面板、通知
  • 管理用户输入、队列、流式输出、会话切换
  • 把输入交给 query loop
  1. 状态管理层 文件： claude-code-source-code/src/state/AppStateStore.ts claude-code-source-code/src/state/onChangeAppState.ts claude-code-source-code/src/bootstrap/state.ts

职责：

  • 保存当前会话的全局状态
  • 包括模型、权限模式、MCP 连接、任务、通知、bridge 状态、文件历史、todo、插件等
  • 状态变化时同步回配置、外部元数据、权限模式
  1. 模型查询循环 文件： claude-code-source-code/src/query.ts claude-code-source-code/src/constants/prompts.ts claude-code-source-code/src/utils/messages.ts

职责：

  • 组装发给模型的消息和 system prompt
  • 流式接收 assistant 输出
  • 识别 tool_use
  • 调度工具执行
  • 把 tool_result 再塞回消息流，继续下一轮
  • 直到模型停止，不再请求工具

这是项目最核心的 agent loop。

  1. 工具层 文件： claude-code-source-code/src/tools.ts claude-code-source-code/src/Tool.ts claude-code-source-code/src/tools/BashTool/BashTool.ts claude-code-source-code/src/tools/FileReadTool/FileReadTool.ts claude-code-source-code/src/tools/FileEditTool/FileEditTool.ts

职责：

  • 定义所有内置工具
  • 根据权限模式、feature gate、当前环境决定哪些工具可用
  • 每个工具负责：
    • 输入 schema
    • 执行逻辑
    • UI 展示
    • 映射为 tool_result
  1. 扩展层 文件： claude-code-source-code/src/commands.ts

职责：

  • 注册 slash commands
  • 加载 skills、plugins、bundled skills、MCP commands
  • 按当前环境过滤可见命令

运行逻辑 最重要的一条主链路是：

  1. 用户在 REPL 输入内容
  2. REPL.tsx 通过 claude-code-source-code/src/utils/handlePromptSubmit.ts 处理输入
  3. 输入被转成消息，附带上下文、图片、引用、命令队列等
  4. REPL.tsx 调用 query()
  5. claude-code-source-code/src/query.ts 把消息、system prompt、tools 发给模型
  6. 如果模型返回普通文本，就流式渲染到界面
  7. 如果模型返回 tool_use，query loop 会找到对应 Tool 实现并执行
  8. 工具输出被包装成 tool_result
  9. tool_result 作为新的 user message 再次送回模型
  10. 重复，直到本轮结束

也就是：

用户输入 -> REPL -> query loop -> 模型 -> tool_use -> Tool执行 -> tool_result -> 模型 -> 最终回答

这就是 Claude Code 类项目的标准 agent 回路。

几个关键设计点

  1. cli.tsx 和 main.tsx 分层很清楚。 cli.tsx 追求“启动快、按路径懒加载”，main.tsx 才负责完整初始化。
  2. commands 和 tools 是两套系统。
  • commands 是 /help、/config、/model 这种 slash command
  • tools 是模型能主动调用的能力，例如读文件、写文件、跑 shell、搜索
  1. REPL.tsx 很重，但它更像“编排器”。 它不自己实现工具，也不直接写核心算法，而是协调：
  • 输入
  • 消息渲染
  • query 状态
  • 权限弹窗
  • 任务队列
  • bridge / remote / MCP
  1. query.ts 才是 agent runtime 核心。 如果你只想理解“这个项目怎么工作”，优先看它。

你可以按这个顺序读代码 建议阅读顺序：

  1. claude-code-source-code/src/entrypoints/cli.tsx
  2. claude-code-source-code/src/main.tsx
  3. claude-code-source-code/src/commands.ts
  4. claude-code-source-code/src/tools.ts
  5. claude-code-source-code/src/Tool.ts
  6. claude-code-source-code/src/constants/prompts.ts
  7. claude-code-source-code/src/query.ts
  8. claude-code-source-code/src/screens/REPL.tsx
  9. 再挑一个具体工具，例如 claude-code-source-code/src/tools/FileReadTool/ FileReadTool.ts